C sample programs
This topic describes the C sample programs that Thales includes in ProtectToolkit-C SDK package. The sample programs include a variety of PKCS#11 applications. Unless specifically stated, the source code provided with the ProtectToolkit-C SDK product can be modified or incorporated into other programs. Refer to the following sections:
Compiling the C sample programs
Compile the C sample programs before attempting to run and use them. To compile the C sample programs, refer to the compilation procedure that is applicable to your release:
-
Compiling the C sample programs on ProtectToolkit 7.2.3 or newer
-
Compiling the C sample programs on ProtectToolkit 7.2.1 or older
Note
If you are using ProtectToolkit 7.3.0, refer to Compiling the C sample programs on ProtectToolkit 7.2.1 or older because ProtectToolkit 7.3.0 precedes the release of ProtectToolkit 7.2.3.
Compiling the C sample programs on ProtectToolkit 7.2.3 or newer
This section describes how to compile the C sample programs on ProtectToolkit 7.2.3 or newer. First refer to the Prerequisites and then to To compile the C sample programs on ProtectToolkit 7.2.3 or newer.
Prerequisites
Before compiling the samples, complete the following steps on the ProtectToolkit 7 client machine:
-
Move the C samples out of the installation directory.
-
Download and install Microsoft Visual Studio 2019 or newer.
-
Download and install CMake 3.10 or newer.
-
Move the C samples out of the installation directory.
-
Download and install one of the following C compilers.
-
GCC (Linux)
-
Clang (Linux)
-
XL C (AIX)
-
-
Download and install CMake 3.10 or newer.
To compile the C sample programs on ProtectToolkit 7.2.3 or newer
-
Open a Visual Studio command prompt.
-
Set the CPROVDIR environment variable to the path of the ProtectToolkit-C SDK package.
set CPROVDIR=<path\to\ptk-csdk>
set CPROVDIR=C:\Program Files\Safenet\ProtectToolkit 7\C SDK -
Navigate to the samples directory.
Note
The samples directory should have been moved outside the ProtectToolkit-C SDK installation directory before beginning the procedure. To avoid running into issues, move samples out of the installation directory before modifying, compiling, or running them.
cd <path\to\samples>
cd C:\Users\Administrator\Desktop\samples -
Generate the build project.
cmake -S <path\to\samples> -B build
cmake -S C:\Users\Administrator\Desktop\samples -B build -
Compile the binaries.
cmake --build <build_dir>
cmake --build build
The samples have been successfully compiled.
-
Set the CPROVDIR environment variable to the path of the ProtectToolkit-C SDK package.
set CPROVDIR=/opt/safenet/protecttoolkit7/cpsdk/
-
Navigate to the samples directory.
Note
The samples directory should have been moved outside the ProtectToolkit-C SDK installation directory before beginning the procedure. To avoid running into issues, move samples out of the installation directory before modifying, compiling, or running them.
cd <path/to/samples>
cd /home/user/ptk_c_samples/ -
Generate the build project.
cmake -S <path/to/samples> -B build
cmake -S /home/user/ptk_c_samples/ -B build -
Compile the binaries.
cmake --build <build_dir>
cmake --build build
The samples have been successfully compiled.
Compiling the C sample programs on ProtectToolkit 7.2.1 or older
This section describes how to compile the C sample programs on ProtectToolkit 7.2.1 or older. First refer to the Prerequisites and then to To compile the C sample programs on ProtectToolkit 7.2.1 or older.
Prerequisites
Before compiling the samples, complete the following steps on the ProtectToolkit 7 client machine:
-
Move the C samples out of the installation directory.
-
Download and install Microsoft Visual Studio 2019 or newer.
-
Move the C samples out of the installation directory.
-
Download and install one of the following C compilers.
-
GCC (Linux)
-
Clang (Linux)
-
XL C (AIX)
-
To compile the C sample programs on ProtectToolkit 7.2.1 or older
Complete either of the following two procedures:
-
Compile the programs by using the developer command prompt included with Visual Studio. For more information, refer to Walkthrough: Compile a C program on the command line.
-
Compile the programs by using the Visual Studio IDE (integrated development environment). For more information, refer to Walkthrough: Working with Projects and Solutions (C++).
-
Navigate to the samples directory.
Note
The samples directory should have been moved outside the ProtectToolkit-C SDK installation directory before beginning the procedure. To avoid running into issues, move samples out of the installation directory before modifying, compiling, or running them.
cd <path/to/samples>
cd /home/user/ptk_c_samples/ -
Use the make program to build the sample.
% make
The samples have been successfully compiled.
Running and using the C sample programs
This section describes how to run and use the provided C sample programs. Refer to the following subsections:
Thales also includes some additional C sample programs in the ProtectToolkit-C SDK package. For more information about the functionality of these programs refer to the description provided at the top of the source file for each of them.
ctdemo
Run ctdemo by navigating to the samples directory from a command-line interface and running ctdemo.
This sample program sets up a four-token key profile that can be used for an electronic commerce trading application. The token profiles include a sample customer, merchant, bank and certifying authority. The application exchanges public keys between each of the tokens and, where CA mechanism extensions are supported, ProtectToolkit-C generates certificates for the public keys.
ProtectToolkit-C must be configured to have at least four slots and tokens for this demonstration program to operate correctly.
Arguments
ctdemo -s<slotID> -m<modulus size> -q -f -x
Options
| Option | Description |
|---|---|
| -q | Quick. Does not prompt for values but uses defaults. |
| -f | Force. Does not warn about overwriting token contents. |
| -m | Specify modulus size. |
| -s | First slot number to use. |
| -x | Extended. Creates more keys. |
Defaults
Security Officer (SO) PIN = 9999
| Slot | Token label | PIN |
|---|---|---|
| 0 | Alice | 0000 |
| 1 | NAB | 1111 |
| 2 | Meyer | 2222 |
| 3 | SAFENET | 3333 |
Note
This will overwrite the contents of all of the above tokens.
fcrypt
Run fcrypt by navigating to the samples directory from a command-line interface and running fcrypt.
This sample program uses the recipient's public key and sender's private key to encrypt and sign the contents of a file. Random transport keys for triple DES are generated for the bulk file content encryption. Alternately the password-based encryption (PBE) variant can be used so that only the password needs to be shared and no public keys/certificates need to be exchanged.
Arguments
fcrypt [-d] [-t] [-o<outfile>] -p<password> infile
fcrypt [-d] [-t] [-o<outfile>] -s<key> -r<key> infile
Note
Correct usage is to either to provide a PBE-password, or to provide a sender and recipient key.
Options
| Option | Description |
|---|---|
| -h | View help |
| -d | Decrypt instead of encrypt |
| -o | Output file name |
| -p | PBE password |
| -r | Recipient key name |
| -s | Sender key name |
| -t | Report timing info |
Key naming syntax
<token name>(<user pin>)/<key name>
for example, -s"Alice(0000)/Sign"
Note
fcrypt is also provided as an example tutorial in API Tutorial: Development of a Sample Application.
